
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Directives - vue.js</title>
        <meta charset="utf-8">
        <meta name="description" content="Vue.js - Intuitive, Fast and Composable MVVM for building interactive interfaces.">
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
        <link href='http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,600|Lato|Inconsolata' rel='stylesheet' type='text/css'>
        <link rel="icon" href="/images/logo.png" type="image/x-icon">
        <script>
            window.PAGE_TYPE = "api"
        </script>
        <link rel="stylesheet" href="/css/page.css" type="text/css">
        <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-46852172-1', 'vuejs.org');
  ga('send', 'pageview');
</script>
        <script src="/js/vue.min.js"></script><script src="https://cdn.jsdelivr.net/gh/shentao/vuejs-outdated-docs-modal@v1.3/prompt.min.js"></script>
    </head>
    <body>
        <div id="mobile-bar">
            <a class="menu-button"></a>
            <a class="logo" href="/"></a>
        </div>
        
            <div id="header">
    <a id="logo" href="/">
        <img src="/images/logo.png">
        <span>Vue.js</span>
    </a>
    <ul id="nav">
        <li><a href="/guide/" class="nav-link">Guide</a></li>
<li><a href="/api/" class="nav-link current">API Reference</a></li>
<li><a href="/examples/" class="nav-link">Examples</a></li>
<li><a href="/blog/" class="nav-link">Blog</a></li>
<li><a href="https://github.com/yyx990803/vue" target="_blank" class="nav-link">GitHub</a></li>
    </ul>
</div>
            <div id="main">
                
                    
    <div class="sidebar">
    <ul class="main-menu">
        <li><a href="/guide/" class="nav-link">Guide</a></li>
<li><a href="/api/" class="nav-link current">API Reference</a></li>
<li><a href="/examples/" class="nav-link">Examples</a></li>
<li><a href="/blog/" class="nav-link">Blog</a></li>
<li><a href="https://github.com/yyx990803/vue" target="_blank" class="nav-link">GitHub</a></li>
    </ul>
    <div class="list">
        <h2>Api</h2>
        <ul class="menu-root">
            
                <li><a href="/api/index.html" class="sidebar-link">Overview</a></li>
            
                <li><a href="/api/options.html" class="sidebar-link">Component Options</a></li>
            
                <li><a href="/api/instance-properties.html" class="sidebar-link">Instance Properties</a></li>
            
                <li><a href="/api/instance-methods.html" class="sidebar-link">Instance Methods</a></li>
            
                <li><a href="/api/global-api.html" class="sidebar-link">Global API</a></li>
            
                <li><a href="/api/directives.html" class="sidebar-link current">Directives</a></li>
            
                <li><a href="/api/filters.html" class="sidebar-link">Filters</a></li>
            
        </ul>
    </div>
</div>


<div class="content api with-sidebar">
    <h1>Directives</h1>
    <div id="ad">
        <script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=vuejs" id="_carbonads_js"></script>
    </div>
    <h2 id="Reactive_Directives">Reactive Directives</h2><blockquote>
<p>These directives can bind themselves to a property on the Vue instance, or to an expression which is evaluated in the context of the instance. When the value of the underlying property or expression changes, the <code>update()</code> function of these directives will be called asynchronously on next tick.</p>
</blockquote>
<h3 id="v-text">v-text</h3><p>Updates the element’s <code>textContent</code>.</p>
<p>Internally, &#123;&#123; Mustache &#125;&#125; interpolations are also compiled as a <code>v-text</code> directive on a textNode.</p>
<h3 id="v-html">v-html</h3><p>Updates the element’s <code>innerHTML</code>.</p>
<p class="tip">Using <code>v-html</code> with user-supplied data can be dangerous. It is suggested that you only use <code>v-html</code> when you are absolutely sure about the security of the data source, or pipe it through a custom filter that sanitizes untrusted HTML.</p>

<h3 id="v-show">v-show</h3><ul>
<li>This directive can trigger transitions.</li>
</ul>
<p>Set the element’s display to <code>none</code> or its original value, depending on the truthy-ness of the binding’s value.</p>
<h3 id="v-class">v-class</h3><ul>
<li>This directive accepts an optional argument.</li>
</ul>
<p>If no argument is provided, it will add the binding’s value to the element’s classList, and update the class as the value changes.</p>
<p>If a directive argument is provided, the argument will be the class to be toggled depending on the binding value’s truthy-ness. Combined with multiple clauses this can be pretty useful:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">span</span> <span class="attribute">v-class</span>=<span class="value">"</span><br><span class="line">  red    : hasError,</span><br><span class="line">  bold   : isImportant,</span><br><span class="line">  hidden : isHidden</span><br><span class="line">"</span>&gt;</span><span class="tag">&lt;/<span class="title">span</span>&gt;</span></span><br></pre></td></tr></table></figure>
<h3 id="v-attr">v-attr</h3><ul>
<li>This directive requires an argument.</li>
</ul>
<p>Updates the element’s given attribute (indicated by the argument).</p>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">canvas</span> <span class="attribute">v-attr</span>=<span class="value">"width:w, height:h"</span>&gt;</span><span class="tag">&lt;/<span class="title">canvas</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>Internally, &#123;&#123; Mustache &#125;&#125; interpolations inside attributes are compiled into computed <code>v-attr</code> directives.</p>
<p class="tip">You should use <code>v-attr</code> instead of mustache binding when setting the <code>src</code> attribute on <code>&lt;img&gt;</code> elements. Your templates are parsed by the browser before being compiled by Vue.js, so the mustache binding will cause a 404 when the browser tries to fetch it as the image’s URL.</p>

<h3 id="v-style">v-style</h3><ul>
<li>This directive accepts an optional argument.</li>
</ul>
<p>Apply inline CSS styles to the element.</p>
<p>When there is no argument, the bound value can either be a String or an Object.</p>
<ul>
<li>If it’s a String, it will be set as the element’s <code>style.cssText</code>.</li>
<li>If it’s an Object, each key/value pair will be set on the element’s <code>style</code> object.</li>
</ul>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-style</span>=<span class="value">"myStyles"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<figure class="highlight js"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// myStyles can either be a String:</span></span><br><span class="line"><span class="string">"color:red; font-weight:bold;"</span></span><br><span class="line"><span class="comment">// or an Object:</span></span><br><span class="line">&#123;</span><br><span class="line">  color: <span class="string">'red'</span>,</span><br><span class="line">  <span class="comment">// both camelCase and dash-case works</span></span><br><span class="line">  fontWeight: <span class="string">'bold'</span>,</span><br><span class="line">  <span class="string">'font-size'</span>: <span class="string">'2em'</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>
<p>When there is an argument, it will be used as the CSS property to apply. Combined with multiple clauses you can set multiple properties together:</p>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-style</span>=<span class="value">"</span><br><span class="line">  top: top + 'px',</span><br><span class="line">  left: left + 'px',</span><br><span class="line">  background-color: 'rgb(0,0,' + bg + ')'</span><br><span class="line">"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p><code>v-style</code> is also smart to detect any required browser vendor prefixes, so you can just use the un-prefixed version:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">&lt;!-- will use -webkit-transform if needed, for example --&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-style</span>=<span class="value">"transform: 'scale(' + scale + ')'"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p class="tip">It is recommended to use <code>v-style</code> instead of mustache bindings inside <code>style</code> attribute because Internet Explorer, regardless of version, will remove invalid inline styles when parsing the HTML.</p>

<h3 id="v-on">v-on</h3><ul>
<li>This directive requires an argument.</li>
<li>This directive requires the value to be a Function or a statement.</li>
</ul>
<p>Attaches an event listener to the element. The event type is denoted by the argument. It is also the only directive that can be used with the <code>key</code> filter. For more details see <a href="/guide/events.html">Listening for Events</a>.</p>
<h3 id="v-model">v-model</h3><ul>
<li>This directive can only be used on <code>&lt;input&gt;</code>, <code>&lt;select&gt;</code> or <code>&lt;textarea&gt;</code> elements.</li>
<li>Directive params: <a href="/guide/forms.html#Lazy_Updates"><code>lazy</code></a>, <a href="/guide/forms.html#Casting_Value_as_Number"><code>number</code></a>, <a href="/guide/forms.html#Dynamic_Select_Options"><code>options</code></a>, <a href="/guide/forms.html#Input_Debounce"><code>debounce</code></a></li>
</ul>
<p>Create a two-way binding on a form input element. Data is synced on every <code>input</code> event by default. For detailed examples see <a href="/guide/forms.html">Handling Forms</a>.</p>
<h3 id="v-if">v-if</h3><ul>
<li>This directive can trigger transitions.</li>
</ul>
<p>Conditionally insert / remove the element based on the truthy-ness of the binding value. If the element is a <code>&lt;template&gt;</code> element, its content will be extracted as the conditional block.</p>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">template</span> <span class="attribute">v-if</span>=<span class="value">"test"</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">p</span>&gt;</span>hello<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">p</span>&gt;</span>world<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">template</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>Will render:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">&lt;!--v-if-start--&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">p</span>&gt;</span>hello<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">p</span>&gt;</span>world<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line"><span class="comment">&lt;!--v-if-end--&gt;</span></span><br></pre></td></tr></table></figure>
<h3 id="v-repeat">v-repeat</h3><ul>
<li>This directive creates child Vue instances.</li>
<li>This directive requires the value to be an Array, Object or Number.</li>
<li>This directive can trigger transitions.</li>
<li>This directive accepts an optional argument.</li>
<li>Directive params: <a href="/guide/list.html#Using_track-by"><code>track-by</code></a></li>
</ul>
<p>Create a child ViewModel for every item in the binding Array or Object. If the value is a whole Number then that many child ViewModels are created. These child ViewModels will be automatically created / destroyed when mutating methods, e.g. <code>push()</code>, are called on the Array or Object, or the number is increased or decreased.</p>
<p>When no argument is provided, the child ViewModel will directly use the assigned element in the Array as its <code>$data</code>. If the value is not an object, a wrapper data object will be created and the value will be set on that object using the alias key <code>$value</code>.</p>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">ul</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">li</span> <span class="attribute">v-repeat</span>=<span class="value">"users"</span>&gt;</span></span><br><span class="line">    &#123;&#123;name&#125;&#125; &#123;&#123;email&#125;&#125;</span><br><span class="line">  <span class="tag">&lt;/<span class="title">li</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">ul</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>If an argument is provided, a wrapper data object will always be created, using the argument string as the alias key. This allows for more explicit property access in templates:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">ul</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">li</span> <span class="attribute">v-repeat</span>=<span class="value">"user : users"</span>&gt;</span></span><br><span class="line">    &#123;&#123;user.name&#125;&#125; &#123;&#123;user.email&#125;&#125;</span><br><span class="line">  <span class="tag">&lt;/<span class="title">li</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">ul</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>For detailed examples, see <a href="/guide/list.html">Displaying a List</a>.</p>
<h3 id="v-with">v-with</h3><ul>
<li>This directive can only be used with <code>v-component</code>.</li>
<li>This directive accepts only keypaths, no expressions.</li>
</ul>
<p>Allows a child ViewModel to inherit data from the parents. You can either pass in an Object which will be used as the <code>data</code> option, or bind individual parent properties to the child with different keys. This directive must be used in combination with <code>v-component</code>.</p>
<p>Example inheriting an object:</p>
<figure class="highlight js"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// parent data looks like this</span></span><br><span class="line">&#123;</span><br><span class="line">  user: &#123;</span><br><span class="line">    name: <span class="string">'Foo Bar'</span>,</span><br><span class="line">    email: <span class="string">'foo@bar.com'</span></span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">my-component</span> <span class="attribute">v-with</span>=<span class="value">"user"</span>&gt;</span></span><br><span class="line">  <span class="comment">&lt;!-- you can access properties without `user.` --&gt;</span></span><br><span class="line">  &#123;&#123;name&#125;&#125; &#123;&#123;email&#125;&#125;</span><br><span class="line"><span class="tag">&lt;/<span class="title">my-component</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>Example inheriting individual properties (using the same data):</p>
<figure class="highlight plain"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">&#60;my-component v-with=&#34;myName: user.name, myEmail: user.email&#34;&#62;&#10;  &#60;!-- you can access properties with the new keys --&#62;&#10;  &#123;&#123;myName&#125;&#125; &#123;&#123;myEmail&#125;&#125;&#10;&#60;/my-component&#62;</span><br></pre></td></tr></table></figure>
<h3 id="v-events">v-events</h3><ul>
<li>This directive can only be used with <code>v-component</code>.</li>
<li>This directive accepts either a method name, or a single expression statement.</li>
</ul>
<p>Allows a parent instance to listen to events on a child instance. The difference from <code>v-on</code> is that <code>v-events</code> listens to Vue’s component system events created via <code>vm.$emit()</code> rather than DOM events. This directive allows more decoupled parent-child communication without having to hard-code event listeners into the parent component. Note that it can only be used together with <code>v-component</code>, i.e. on the root element of a child component.</p>
<p><strong>Example:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">&lt;!-- inside parent template --&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-component</span>=<span class="value">"child"</span> <span class="attribute">v-events</span>=<span class="value">"change: onChildChange"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>When the child component calls <code>this.$emit(&#39;change&#39;, ...)</code>, the parent’s <code>onChildChange</code> method will be invoked with additional arguments passed to <code>$emit()</code>.</p>
<h2 id="Literal_Directives">Literal Directives</h2><blockquote>
<p>Literal directives treat their attribute value as a plain string; they do not attempt to bind themselves to anything. All they do is executing the <code>bind()</code> function with the string value once. Literal directives accept mustache expressions inside their value, but these expressions will be evaluated only once on first compile and do not react to data changes.</p>
</blockquote>
<h3 id="v-component">v-component</h3><ul>
<li>Directive params: <a href="/guide/components.html#Dynamic_Components"><code>keep-alive</code></a>, <a href="/guide/components.html#wait-for"><code>wait-for</code></a>, <a href="/guide/components.html#transition-mode"><code>transition-mode</code></a>, <a href="/guide/components.html#Inline_Template"><code>inline-template</code></a></li>
<li>Can be made reactive with mustaches</li>
</ul>
<p>Compile this element as a child ViewModel with a registered component constructor. This can be used with <code>v-with</code> to inehrit data from the parent. For more details see <a href="/guide/components.html">Component System</a>.</p>
<h3 id="v-partial">v-partial</h3><ul>
<li>Can be made reactive with mustaches</li>
</ul>
<p>Replace the element’s innerHTML with a registered partial. Partials can be registered with <code>Vue.partial()</code> or passed inside the <code>partials</code> option.</p>
<p>Using the mustache tag inside <code>v-partial</code> makes it reactive:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">&lt;!-- content will change based on vm.partialId --&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-partial</span>=<span class="value">"&#123;&#123;partialId&#125;&#125;"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>You can also use this syntax (which doesn’t support reactivity):</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">div</span>&gt;</span>&#123;&#123;&gt; my-partial&#125;&#125;<span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<h3 id="v-transition">v-transition</h3><ul>
<li>Can be made reactive with mustaches</li>
</ul>
<p>Notify Vue.js to apply transitions to this element. The transition classes are applied when certain transition-triggering directives modify the element, or when the Vue instance’s DOM manipulation methods are called.</p>
<p>For details, see <a href="/guide/transitions.html">the guide on transitions</a>.</p>
<h3 id="v-ref">v-ref</h3><p>Register a reference to a child component on its parent for easier access. Only respected when used in combination with <code>v-component</code> or <code>v-repeat</code>. The component instance will be accessible on its parent’s <code>$</code> object. For an example, see <a href="/guide/components.html#Child_Reference">child reference</a>.</p>
<p>When used with <code>v-repeat</code>, the value will be an Array containing all the child Vue instances corresponding to the Array they are bound to.</p>
<h3 id="v-el">v-el</h3><p>Register a reference to a DOM element on its owner Vue instance for easier access. e.g. <code>&lt;div v-el=&quot;hi&quot;&gt;</code> will be accessible as <code>vm.$$.hi</code>.</p>
<h2 id="Empty_Directives">Empty Directives</h2><blockquote>
<p>Empty directives do not require and will ignore their attribute value.</p>
</blockquote>
<h3 id="v-pre">v-pre</h3><p>Skip compilation for this element and all its children. Skipping large numbers of nodes with no directives on them can speed up compilation.</p>
<h3 id="v-cloak">v-cloak</h3><p>This property remains on the element until the associated ViewModel finishes compilation. Combined with CSS rules such as <code>[v-cloak] { display: none }</code>, this directive can be used to hide un-compiled mustache bindings until the ViewModel is ready.</p>

    <div class="footer">Caught a mistake or want to contribute to the documentation? <a href="https://github.com/vuejs/vuejs.org" target="_blank">Fork this site on Github</a>!</div>
</div>
                
            </div>
            <script src="/js/smooth-scroll.min.js"></script>
            <script src="/js/common.js"></script>
        
    </body>
</html>